/*
 * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.util;

/**
 * ListIterator 是 Java 中的一个接口，它扩展了 Iterator 接口，专门用于遍历 List 集合。ListIterator 提供了比 Iterator 更多的功能，尤其是在双向遍历列表和修改列表内容方面。
 * @see Collection
 * @see List
 * @see Iterator
 * @see Enumeration
 * @see List#listIterator()
 * @since   1.2
 */
public interface ListIterator<E> extends Iterator<E> {
    // Query Operations

    /**
     * 判断迭代器是否还有下一个元素
     */
    boolean hasNext();

    /**
     * 返回迭代器的下一个元素，并将迭代器的位置向前移动
     * @throws NoSuchElementException 如果迭代没有下一个元素
     */
    E next();

    /**
     * 判断迭代器是否还有前一个元素
     */
    boolean hasPrevious();

    /**
     * 返回迭代器的前一个元素，并将迭代器的位置向后移动。
     */
    E previous();

    /**
     * 返回下一次调用 next() 方法时返回的元素的索引
     */
    int nextIndex();

    /**
     *：返回下一次调用 previous() 方法时返回的元素的索引
     */
    int previousIndex();


    // Modification Operations

    /**
     * 从底层集合中删除此迭代器返回的最后一个元素（可选操作）。
     * 此方法只能调用一次next()
     * 如果底层集合在迭代过程中以任何方式进行修改而不是通过调用此方法，则迭代器的行为是未指定的。
     * @throws UnsupportedOperationException 如果 remove操作不会被这个迭代器支持
     * @throws IllegalStateException         如果 next方法尚未被调用，或者 remove方法在上次调用 next方法之后已经被调用
     **/
    void remove();

    /**
     * ListIterator 接口中的 set 方法用于替换由 ListIterator 上的最后一次 next 或 previous 调用返回的元素。
     * 这意味着在调用 set 方法之前，必须先调用 next 或 previous 方法，否则会抛出。
     *
     * @param e 用于替换由 next或 previous返回的最后一个元素的元素
     * @throws UnsupportedOperationException 如果 set操作不受此列表迭代器支持
     * @throws ClassCastException            如果指定元素的类阻止将其添加到此列表中
     * @throws IllegalArgumentException      如果指定元素的某些方面阻止将其添加到此列表中
     * @throws IllegalStateException         如果 next和 previous都没有被调用，或者 remove或 add在上次调用 next调用了 next或 previous
     */
    void set(E e);

    void add(E e);
}
